<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>recvmsg</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4>NAME</h4><blockquote>
recvmsg - receive a message from a socket
</blockquote><h4>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="syssocket.h.html">sys/socket.h</a>&gt;

ssize_t recvmsg(int <I>socket</I>, struct msghdr *<I>message</I>, int <I>flags</I>);
</code>
</pre>
</blockquote><h4>DESCRIPTION</h4><blockquote>
The
<i>recvmsg()</i>
function receives a message from a connection-mode or connectionless-mode
socket.  It is normally used with connectionless-mode
sockets because it permits
the application to retrieve the source address of received data.
<p>
The function takes the following arguments:
<dl compact>

<dt><I>socket</I><dd>Specifies the socket file descriptor.

<dt><I>message</I><dd>Points to a <B>msghdr</B> structure, containing both the buffer to
store the source address and the buffers for the incoming message.
The length and format of the address depend on the address family
of the socket.  The <B>msg_flags</B> member is ignored on input, but
may contain meaningful values on output.

<dt><I>flags</I><dd>Specifies the type of message reception.  Values of this argument are formed
by logically OR'ing zero or more of the following values:
<dl compact>

<dt>MSG_OOB<dd>Requests out-of-band data.
The significance and semantics of out-of-band data are protocol-specific.

<dt>MSG_PEEK<dd>Peeks at the incoming message.

<dt>MSG_WAITALL<dd>Requests that the function block until the full amount of data requested can
be returned.  The function may return a smaller amount of data if a signal is
caught, 
if the connection is terminated,
if MSG_PEEK was specified,
or if an error is pending for the socket.

</dl>
<p>
</dl>
<p>
The
<i>recvmsg()</i>
function receives messages from unconnected or connected sockets and returns
the length of the message.
<p>
The
<i>recvmsg()</i>
function returns the total length of the message.  For message-based sockets
such as SOCK_DGRAM and SOCK_SEQPACKET, the entire message must be read in a
single operation.  If a message is too long to fit in the supplied buffers,
and MSG_PEEK is not set in the <I>flags</I> argument, the excess bytes are
discarded, and MSG_TRUNC is set in the <B>msg_flags</B> member of the
<B>msghdr</B> structure.  For stream-based sockets such as SOCK_STREAM, message
boundaries are ignored.  In this case, data is returned to the user as soon as
it becomes available, and no data is discarded.
<p>
If the MSG_WAITALL flag is not set, data will be returned
only up to the end of the first message.
<p>
If no messages are available at the socket and O_NONBLOCK is
not set on the socket's file descriptor,
<i><a href="recvfrom.html">recvfrom()</a></i>
blocks until a message arrives.
If no messages are available at the socket and O_NONBLOCK is
set on the socket's file descriptor,
<i><a href="recvfrom.html">recvfrom()</a></i>
function fails and sets <I>errno</I> to [EAGAIN] or [EWOULDBLOCK].
<p>
In the <B>msghdr</B> structure, the <B>msg_name</B> and <B>msg_namelen</B>
members specify the source address if the socket is unconnected.
If the socket is connected, the <B>msg_name</B> and <B>msg_namelen</B> members
are ignored.  The <B>msg_name</B> member may be a null pointer if no names are
desired or required.  
The 
<I>msg_iov</I>
and 
<I>msg_iovlen</I>
fields are used to specify
where the received data will be stored. 
<I>msg_iov</I>
points
to an array of 
<B>iovec</B>
structures; 
<I>msg_iovlen</I>
must be set
to the dimension of this array. In each 
<B>iovec</B>
structure,
the 
<I>iov_base</I>
field specifies a storage area and the
<I>iov_len</I>
field gives its size in bytes. Each storage area
indicated by 
<I>msg_iov</I>
is filled with received data in turn 
until all of the received data is stored or all of the 
areas have been filled.
<p>
On successful completion, the <B>msg_flags</B> member of the message
header is the bitwise-inclusive OR of all of the following flags that indicate
conditions detected for the received message:.
<dl compact>

<dt>MSG_EOR<dd>End of record was received (if supported by the protocol).

<dt>MSG_OOB<dd>Out-of-band data was received.

<dt>MSG_TRUNC<dd>Normal data was truncated.

<dt>MSG_CTRUNC<dd>Control data was truncated.

</dl>
</blockquote><h4>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>recvmsg()</i>
returns the length of the message in bytes.  If no messages are available to
be received and the peer has performed an orderly shutdown,
<i>recvmsg()</i>
returns 0.
Otherwise, -1 is returned and <I>errno</I> is set to indicate the
error.
</blockquote><h4>ERRORS</h4><blockquote>
The
<i>recvmsg()</i>
function will fail if:
<dl compact>

<dt>[EAGAIN] or [EWOULDBLOCK]<dd><br>
The socket's file descriptor is marked O_NONBLOCK and no data is waiting to
be received; or MSG_OOB is set and no out-of-band data is available and either
the socket's file descriptor is marked O_NONBLOCK or the socket does not
support blocking to await out-of-band data.

<dt>[EBADF]<dd><index term="EBADF, in "></index>
The <I>socket</I> argument is not a valid open file descriptor.

<dt>[ECONNRESET]<dd>A connection was forcibly closed by a peer.

<dt>[EFAULT]<dd>The 
<I>message</I>
parameter,
or storage pointed to by the 
<I>msg_name</I>,
<I>msg_control</I>
or 
<I>msg_iov</I>
fields of the 
<I>message</I>
parameter, or storage pointed to by the
<B>iovec</B>
structures pointed to by the 
<I>msg_iov</I>
field can not be accessed or written.

<dt>[EINTR]<dd>This function was interrupted by a signal before any data was available.

<dt>[EINVAL]<dd>The sum of the <B>iov_len</B> values overflows an <B>ssize_t</B>.
or the MSG_OOB flag is set and no out-of-band data is available.

<dt>[EMSGSIZE]<dd>The
<B>msg_iovlen</B>
member of the
<B>msghdr</B>
structure pointed to by
<I>message</I>
is less than or equal to 0, or is greater than {IOV_MAX}.

<dt>[ENOTCONN]<dd>A receive is attempted on a connection-mode socket that is not connected.

<dt>[ENOTSOCK]<dd>The <I>socket</I> argument does not refer to a socket.

<dt>[EOPNOTSUPP]<dd>The specified flags are not supported for this socket type.

<dt>[ETIMEDOUT]<dd>The connection timed out during connection establishment, or due to a
transmission timeout on active connection.

</dl>
<p>
The
<i>recvmsg()</i>
function may fail if:
<dl compact>

<dt>[EIO]<dd>An I error occurred while reading from or writing to the file system.

<dt>[ENOBUFS]<dd>Insufficient resources were available in the system to perform the operation.

<dt>[ENOMEM]<dd>Insufficient memory was available to fulfill the request.

<dt>[ENOSR]<dd>There were insufficient STREAMS resources available for the operation to
complete.

</dl>
</blockquote><h4>APPLICATION USAGE</h4><blockquote>
The
<i><a href="select.html">select()</a></i>
and
<i><a href="poll.html">poll()</a></i>
functions can be used to determine when data is available to be received.
</blockquote><h4>SEE ALSO</h4><blockquote>
<i><a href="poll.html">poll()</a></i>,
<i><a href="recv.html">recv()</a></i>,
<i><a href="recvfrom.html">recvfrom()</a></i>,
<i><a href="select.html">select()</a></i>,
<i><a href="send.html">send()</a></i>,
<i><a href="sendmsg.html">sendmsg()</a></i>,
<i><a href="sendto.html">sendto()</a></i>,
<i><a href="shutdown.html">shutdown()</a></i>,
<i><a href="socket.html">socket()</a></i>,
<i><a href="syssocket.h.html">&lt;sys/socket.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
